﻿<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
    <title></title>
    <style type="text/css">
        .style1
        {
            text-decoration: underline;
        }
        .style2
        {
            width: 100%;
        }
        .style3
        {
            width: 557px;
        }
        .style4
        {
            width: 439px;
        }
        .style5
        {
            width: 414px;
        }
    </style>
</head>
<body>
    <h1>
        <span id="internal-source-marker_0.266968945998761" style="font-size: 48px; font-family: Arial;
            color: #000000; background-color: transparent; font-weight: bold; font-style: normal;
            font-variant: normal; text-decoration: none; vertical-align: baseline;"><span style="font-size: 48px;
                font-family: Arial; color: #000000; background-color: transparent; font-weight: bold;
                font-style: normal; font-variant: normal; text-decoration: none; vertical-align: baseline;">
                Use SAX to </span>Convert XML Document to YAML Format</span></h1>
    <dl>
        <dt>Date</dt>
        <dd>
            2012-04-23</dd>
        <dt>Authors</dt>
        <dd>
            Shaohui Chen</dd>
        <dt>Content</dt>
        <dd>
            <ul>
                <li><a href="#intro" title="Some basic information">Introduction</a></li>
                <li><a href="#lic" title="What you are permitted to do">License</a></li>
                <li><a href="#support" title="What you can use">Currently supported</a></li>
                <li><a href="#getit" title="How to get it">Get the source</a></li>
                <li><a href="#compile" title="How to compile">Compiling this project</a><ul>
                    <li><a href="#usage">Usage</a> </li>
                </ul>
                </li>
                <li><a href="#example" title="Some useful examples">Configuration examples</a>
                    <ul>
                        <li><a href="#namespace" title="Reading file">Namepspace Mapping</a></li>
                        <li><a href="#xpthmapping" title="Reading string">XPath Mpping</a></li>
                        <li><a href="#ignorexpath" title="Writing file">Ignore specific XPath</a></li>
                        <li><a href="#comment" title="Writing string">Display Comment setting</a></li>
                    </ul>
                </li>
                <li></li>
                <li><a href="#algo" title="How we did it">Reference</a></li>
            </ul>
        </dd>
    </dl>
    <h2 id="intro">
        Introduction</h2>
    <p>
        For those who love YAML, but require buzz-word compliance or require XML angle brackets,
        there is a clean option -- a subset of XML which has YAML&#39;s information model,
        but XML&#39;s syntax. Since a YAML stream may not start with a &#39;&lt;&#39; character,
        a YAML implementation could implement an implicit, automatic conversion of XML in
        this schema to the equivalent YAML.&nbsp;
    </p>
    <p>
        SAX (Simple API for XML) is an event-based sequential access parser API developed
        by the XML-DEV mailing list for XML documents. SAX parsers have certain benefits
        over DOM-style parsers. Because SAX Parser is a stream parser, with an event-driven
        API, The quantity of memory that a SAX parser must use in order to function is typically
        much smaller than that of a DOM parser.
    </p>
    <p>
        &nbsp;We hope you enjoy our work and it is useful.
    </p>
    <h2 id="lic">
        License</h2>
    <p>
        We released our software as an OpenSource project. This is one of the project requirements
        and also has our full support. We used the GNU Lesser General Public License that
        can be found in the <kbd>Code</kbd> directory. More information can be found on
        <a href="http://www.gnu.org/" target="_top" title="GNU General Public License">http://www.gnu.org/</a>.
    </p>
    <h2 id="support">
        Currently supported
    </h2>
    <div id="namespace">
        <ul>
            <li class="style1"><strong>Namespace mapping to Yaml tag</strong></li>
        </ul>
        <p>
            <b>Usage:</b>
        </p>
        <p>
            &lt;namespace&gt; &lt;add key="{xmlns}" value="{mapping tag name}"&gt;&lt;/add&gt;
            &lt;/namespace&gt;</p>
        <p>
            <b>Example</b>
        </p>
        <div>
            <table class="style2">
                <tr>
                    <td class="style3">
                        <strong>Configuration</strong>
                    </td>
                    <td>
                        <strong>Description</strong>
                    </td>
                </tr>
                <tr>
                    <td class="style3">
                        &lt;add key="http://www.brics.dk/ixwt/recipes" value="recipes"&gt;
                    </td>
                    <td>
                        mapping namespace "http://www.brics.dk/ixwt/recipes" as tag name: "recipes"
                    </td>
                </tr>
            </table>
        </div>
        <p>
        </p>
    </div>
    <div id="xpthmapping">
        <ul>
            <li class="style1"><strong>Xpath mapping to spec name/value</strong></li>
        </ul>
        <p>
        </p>
        <p>
            <b>Usage:</b>
        </p>
        <p>
            &lt;namespace&gt; &lt;add key="{xmlns}" value="{mapping tag name}"&gt;&lt;/add&gt;
            &lt;/namespace&gt;</p>
        <p>
        </p>
        <p>
            <b>Example</b>
        </p>
        <div>
            <table class="style2">
                <tr>
                    <td class="style4">
                        <strong>Configuration</strong>
                    </td>
                    <td>
                        <strong>Description</strong>
                    </td>
                </tr>
                <tr>
                    <td class="style4">
                        &lt;xpath key=&quot;/root&quot; value=&quot;yaml&quot;&gt;
                    </td>
                    <td>
                        Mapping root element is &quot;root&quot; to &quot;yaml&quot; string
                    </td>
                </tr>
                <tr>
                    <td class="style4">
                        &lt;xpath key=&quot;//express/@name&quot; value=&quot;&quot;&gt;
                    </td>
                    <td>
                        Mapping attribute name is &quot;name&quot; value to empty string
                    </td>
                </tr>
                <tr>
                    <td class="style4">
                        &lt;xpath key=&quot;given&quot; value=&quot;customer name&quot;&gt;&lt;/xpath&gt;
                    </td>
                    <td>
                        Mapping all element name is &quot;given&quot; to &quot;customer name&quot;
                    </td>
                </tr>
                <tr>
                    <td class="style4">
                        &lt;xpath key=&quot;//recipes:recipe[@id=&#39;r104&#39;]&quot; value=&quot;recipeR104&quot;&gt;&lt;/xpath&gt;
                    </td>
                    <td>
                        Mapping pre-condition xpath to &quot;recipeR104&quot;
                    </td>
                </tr>
                <tr>
                    <td class="style4">
                    </td>
                    <td>
                    </td>
                </tr>
                <tr>
                    <td class="style4">
                        &lt;xpath key=&quot;//recipes:date[.=&#39;Fri, 28 May 04&#39;]&quot; value=&quot;Friday,
                        May 28th, 2004&quot;&gt;&lt;/xpath&gt;
                    </td>
                    <td>
                        Mapping value is &quot;Fri, 28 May 04&quot; to value &quot;Friday, May 28th, 2004&quot;
                    </td>
                </tr>
                <tr>
                    <td class="style4">
                    </td>
                    <td>
                    </td>
                </tr>
                <tr>
                    <td class="style4">
                    </td>
                    <td>
                    </td>
                </tr>
                <tr>
                    <td class="style4">
                    </td>
                    <td>
                    </td>
                </tr>
            </table>
        </div>
        <p>
            &nbsp;</p>
    </div>
    <div id="ignorexpath">
        <ul>
            <li class="style1"><strong>Ignore spec xpath</strong></li>
        </ul>
        <p>
            <b>Usage:</b>
        </p>
        <p>
            &lt;ignore&gt; &lt;xpath&gt;{xpath}&lt;/xpath&gt;&lt;/ignore&gt;
        </p>
        <p>
            &nbsp;</p>
        <p>
            <b>Example</b>
        </p>
        <table class="style2">
            <tr>
                <td class="style4">
                    <strong>Configuration</strong>
                </td>
                <td>
                    <strong>Description</strong>
                </td>
            </tr>
            <tr>
                <td class="style4">
                    &lt;xpath&gt;/invoice/number&lt;/xpath&gt;
                </td>
                <td>
                    Ignore absoluate xpath /invoice/number
                </td>
            </tr>
            <tr>
                <td class="style4">
                    address
                </td>
                <td>
                    Ignroe all address element
                </td>
            </tr>
            <tr>
                <td class="style4">
                    &lt;xpath&gt;//recipes:recipe[@id=&#39;r103&#39;]&lt;/xpath&gt;
                </td>
                <td>
                    ignore node recipe with pre condition: @id=&#39;r103&#39;
                </td>
            </tr>
            <tr>
                <td class="style4">
                    xpath&gt;//recipes:description[.=&#39;Some recipes used in the XML tutorial.&#39;]&lt;/xpath&gt;
                </td>
                <td>
                    Ignore node value is &#39;Some recipes used in the XML tutorial.&#39;
                </td>
            </tr>
            <tr>
                <td class="style4">
                    &lt;xpath&gt;//recipes:recipe[2]&lt;/xpath&gt;
                </td>
                <td>
                    Ignore the second recipe node
                </td>
            </tr>
            <tr>
                <td class="style4">
                    &lt;xpath&gt;//recipes:nutrition/@calories&lt;/xpath&gt;
                </td>
                <td>
                    Ignore attribte name is &quot;calories&quot; &nbsp;
                </td>
            </tr>
            <tr>
                <td class="style4">
                    &lt;xpath&gt;//recipes:preparation/*&lt;/xpath&gt;
                </td>
                <td>
                    Ignore all sub-nodes(include attributes) under preparation
                </td>
            </tr>
            <tr>
                <td class="style4">
                </td>
                <td>
                </td>
            </tr>
            <tr>
                <td class="style4">
                </td>
                <td>
                </td>
            </tr>
        </table>
        <p>
        </p>
    </div>
    <div id="comment">
        <ul>
            <li class="style1"><strong>Display comment in output stream</strong></li>
        </ul>
        <p>
            <b>Usage:</b>
        </p>
        <p>
        </p>

        <table class="style2">
            <tr>
                <td class="style5">
                    <strong>Configuration</strong>
                </td>
                <td>
                    <strong>Description</strong>
                </td>
            </tr>
            <tr>
                <td class="style5">
                    &lt;comment&gt;False&lt;/comment&gt;</td>
                <td>
                    Does not display any comment in xml document</td>
            </tr>
            <tr>
                <td class="style5">
                    &lt;comment&gt;True&lt;/comment&gt;</td>
                <td>
                    Disaply comment
                </td>
            </tr>
        </table>

    </div>
    <p />
    <p />
    <p />
    <h2 id="getit">
        Get the source</h2>
    <p>
        We used git and team foundation to manage our code</p>
    <p style="margin-left: 40px">
        git: <a href="https://bitbucket.org/crane/xml2yaml">https://bitbucket.org/crane/xml2yaml</a></p>
    <p style="margin-left: 40px">
        team foundation: <a href="http://workflowprj.codeplex.com">http://workflowprj.codeplex.com</a></p>
    <p style="margin-left: 40px">
        &nbsp;</p>
    <h2 id="compile">
        Compiling this project</h2>
    <p>
        <b>For Window: </b>
    </p>
    <p style="margin-left: 80px">
        msbuild Xml2Yaml.sln(need Microsoft .NET 4.0 support)</p>
    <p>
        <b>For Linux:</b>
    </p>
    <p style="margin-left: 80px">
        mdtool build Xml2Yaml.sln (need Mono Developer support)</p>
    <p id="usage">
        <b>Usage:</b></p>
    <p style="margin-left: 40px">
        Xml2Yaml Source FileName, [Configuration FileName], [Destination FileName]</p>
    <p>
        &nbsp;</p>
    <p>
        &nbsp;</p>
</body>
</html>
